ROS2 命令行工具速查：命令、接口与实例

ros2 命令族是日常调试 ROS2 系统的主要入口：查节点、看话题、测频率、发消息、录数据包都靠它。命令多、参数杂，本文把它们整理成一份速查手册——一级命令总表、各二级命令对应的底层 rclpy 接口，以及 node/topic/service/action/bag 五组常用命令的完整用法与实例。适合刚接触 ROS2 的开发者随手查阅，也想了解"每条命令背后调了什么接口"的读者可以重点看各组命令后的接口清单。

一、一级命令总表

命令	功能
ros2 action	各种动作相关的子命令
ros2 bag	各种 rosbag（数据录制与回放）相关的子命令
ros2 component	各种组件相关的子命令
ros2 daemon	各种守护进程相关的子命令
ros2 doctor	检查 ROS 设置和其他潜在问题
ros2 interface	显示 ROS 接口（msg/srv/action）信息
ros2 launch	运行启动文件
ros2 lifecycle	各种生命周期相关的子命令
ros2 multicast	各种组播相关的子命令
ros2 node	各种节点相关的子命令
ros2 param	各种参数相关的子命令
ros2 pkg	各种包相关的子命令
ros2 run	运行包特定的可执行文件
ros2 security	各种安全相关的子命令
ros2 service	各种服务相关的子命令
ros2 topic	各种主题相关的子命令
ros2 wtf	doctor 的别名

所有命令都支持 命令 -h / 命令 子命令 -h 查看帮助。

二、二级命令与依赖的 rclpy 接口

ros2cli 的命令实现基于 rclpy。了解每条命令依赖的接口，有助于判断它能拿到什么信息、为什么有时会慢（例如需要等待 DDS 发现）。

node 命令

命令	功能
ros2 node info	输出节点信息
ros2 node list	输出可用节点列表

主要依赖的接口：

• node.get_node_names_and_namespaces()：获取所有节点名与命名空间对
• node.get_subscriber_names_and_types_by_node()：获取指定节点的订阅者列表
• node.get_publisher_names_and_types_by_node()：获取指定节点的发布者列表
• node.get_client_names_and_types_by_node()：获取指定节点的 Service 客户端列表
• node.get_service_names_and_types_by_node()：获取指定节点的 Service 服务端列表
• node.get_action_client_names_and_types_by_node() / get_action_server_names_and_types_by_node()：获取指定节点的 Action 客户端/服务端列表

topic 命令

命令	功能
ros2 topic bw	显示主题使用的带宽
ros2 topic delay	显示主题时间戳的延迟
ros2 topic echo	输出主题中的消息
ros2 topic find	输出指定类型的可用主题列表
ros2 topic hz	打印平均接收速率
ros2 topic info	打印主题的相关信息
ros2 topic list	输出可用主题列表
ros2 topic pub	向主题发布消息
ros2 topic type	打印主题的类型

主要依赖的接口：

• node.create_subscription()：创建订阅者
• node.create_timer()：创建定时器，超时触发回调
• rclpy.qos.QoSPresetProfiles：订阅者 QoS 策略配置
• node.get_publishers_info_by_topic()：检查发布者 QoS 配置以兼容所有发布者
• rclpy.qos_event.SubscriptionEventCallbacks：消息丢失回调
• node.get_topic_names_and_types()：获取 topic 名称和消息类型
• node.create_publisher()：创建发布者

service 命令

命令	功能
ros2 service call	调用一个服务
ros2 service find	输出指定类型的可用服务列表
ros2 service list	输出可用服务列表
ros2 service type	输出服务的类型

主要依赖的接口：

• rclpy.create_node()：创建节点
• node.create_client()：创建客户端
• client.call_async()：异步发起服务请求（返回 Future；ros2 service call 内部 spin 等待响应完成，命令行表现为同步等待）
• node.get_service_names_and_types()：获取当前 ROS 图中服务名到服务类型的映射

action 命令

命令	功能
ros2 action info	打印动作的相关信息
ros2 action list	输出动作名称列表
ros2 action send_goal	发送动作目标

主要依赖的接口：

• node.get_action_client_names_and_types_by_node() / get_action_server_names_and_types_by_node()：获取节点的 Action 客户端/服务端列表
• node.get_action_names_and_types()：获取 ROS 图中动作名到类型的映射
• rclpy.create_node()：创建节点
• _rclpy.ActionClient()：创建 Action 客户端
• ActionClient.action_client.send_goal_async()：异步发送目标请求（返回 Future）
• ClientGoalHandle.cancel_goal_async()：取消请求

interface 命令

命令	功能
ros2 interface list	列出所有可用的接口类型
ros2 interface package	输出一个包内可用的接口类型列表
ros2 interface packages	输出提供接口的包列表
ros2 interface proto	输出接口原型
ros2 interface show	输出接口定义

主要依赖 rosidl_runtime_py 提供的工具函数：get_message_interfaces() / get_service_interfaces() / get_action_interfaces()（获取各包接口定义）、message_to_yaml()（接口原型转 YAML 输出）、get_interface_path()（获取接口文件路径）。

param 命令

命令	功能
ros2 param delete	删除参数
ros2 param describe	显示已声明参数的描述信息
ros2 param dump	以 YAML 文件格式显示节点的所有参数
ros2 param get	获取参数
ros2 param list	输出可用参数列表
ros2 param load	为节点加载参数文件
ros2 param set	设置参数

参数操作通过以下服务完成（每个节点自动提供）：

~/describe_parameters
~/get_parameter_types
~/get_parameters
~/list_parameters
~/set_parameters
~/set_parameters_atomically

实现上使用 node.get_node_names_and_namespaces() 定位目标节点，再通过 node.create_client() + client.call_async(request) 异步发送参数服务请求。

bag 命令

命令	功能
ros2 bag convert	根据输入的数据包，使用不同设置写出新的数据包
ros2 bag info	打印数据包的信息
ros2 bag list	打印可用插件的信息
ros2 bag play	从数据包回放 ROS 数据
ros2 bag record	将 ROS 数据记录到数据包
ros2 bag reindex	为数据包重建元数据文件

主要依赖的接口：

• rclcpp::Node：Recorder/Player 的父类
• create_generic_subscription：通用订阅者（GenericSubscription）允许在运行时动态指定消息类型和处理回调
• rclcpp::QoS：自动匹配发布者/订阅者的服务质量配置
• Node::create_service<...>：服务控制接口

rosbag2 的五层架构（User/Python bindings/Transport/Core C++/Storage 插件）与录制回放的内部机制，见rosbag2 录制回放：分层架构、时间控制与存储格式。

其他命令

pkg 命令：create（创建功能包）、executables（列出可执行文件）、list（列出功能包）、prefix（安装路径）、xml（输出 package.xml）。

component 命令：list / load / standalone / types / unload，通过组件容器的 /_container/xxx 服务动态加载/卸载组件。使用流程：将节点编译为动态库并注册（RCLCPP_COMPONENTS_REGISTER_NODE），启动 component_container，再用命令行加载。

daemon 命令：start / status / stop。守护进程是 ros2cli 的后台服务，用于优化节点发现和系统拓扑查询性能——重复执行 ros2 node list 等命令时，第二次明显更快就是它在起作用。

lifecycle 命令：get / list / nodes / set。rclcpp_lifecycle::LifecycleNode 会自动创建以下 topic 与 service：

static const char * pub_transition_event_topic = "~/transition_event";
static const char * srv_change_state_service = "~/change_state";
static const char * srv_get_state_service = "~/get_state";
static const char * srv_get_available_states_service = "~/get_available_states";
static const char * srv_get_available_transitions_service = "~/get_available_transitions";
static const char * srv_get_transition_graph = "~/get_transition_graph";

multicast 命令：receive / send，收发单个 UDP 组播数据包，使用原生 socket，常用于排查组播网络问题。

security 命令：create_enclave / create_keystore / create_permission / generate_artifacts / generate_policy / list_enclaves 等。ROS2 的通信安全（SROS2）由底层 DDS 的安全插件实现，每个参与者需要配置密钥与权限文件，无需额外安装软件。

三、常用命令详解

ros2 node list / info

ros2 node list [-h] [--spin-time SPIN_TIME] [-s] [--no-daemon] [-a] [-c]

• --spin-time：等待发现的轮询时间（秒），不使用守护进程时生效——时间太短可能漏节点，太长使命令变慢
• -a, --all：包含隐藏节点（名称以 _ 开头）
• -c：仅输出节点数量

$ ros2 node list
/minimal_publisher
/minimal_service

输出的节点名称包含命名空间。

ros2 node info [-h] [--spin-time SPIN_TIME] [-s] [--no-daemon] [--include-hidden] node_name

输出指定节点的订阅者、发布者、Service、Action 全景：

$ ros2 node info /minimal_publisher
/minimal_publisher
  Subscribers:
    /parameter_events: rcl_interfaces/msg/ParameterEvent
  Publishers:
    /parameter_events: rcl_interfaces/msg/ParameterEvent
    /rosout: rcl_interfaces/msg/Log
    /topic: std_msgs/msg/String
  Service Servers:
    /minimal_publisher/describe_parameters: rcl_interfaces/srv/DescribeParameters
    /minimal_publisher/get_parameter_types: rcl_interfaces/srv/GetParameterTypes
    ...

每个节点都自动带有 describe_parameters、get_parameters、set_parameters 等参数服务，这是 param 命令能工作的基础。

ros2 topic

查看带宽 ros2 topic bw：

ros2 topic bw [-h] [--window WINDOW] topic

--window（默认 100）为计算速率的窗口大小。注意此带宽反映的是订阅端的接收速率，受平台资源与 QoS 配置影响，可能与发布端不完全匹配。

测量延迟 ros2 topic delay：基于消息 header 中的时间戳计算端到端延迟，窗口默认 10000。消息类型不带 Header 会报错 msg does not have header。

测量频率 ros2 topic hz：

$ ros2 topic hz /topic
average rate: 1.000
        min: 0.999s max: 1.001s std dev: 0.00047s window: 16

同样反映订阅端接收速率；--filter EXPR 可用 Python 表达式过滤消息，--wall-time 在仿真期间未发布 /clock 时使用墙上时钟。

输出消息 ros2 topic echo：

ros2 topic echo [--qos-profile ...] [--qos-depth N] [--field FIELD] [--csv] [--once] [--raw] topic_name [message_type]

要点：

• 默认 QoS 预设为 sensor_data（best_effort），与 reliable 发布者不通；可用 --qos-reliability reliable 等参数覆盖
• --field pose.pose.position 用 . 路径只输出子字段
• --once 打印一条后退出，适合脚本
• 同名话题上有多种消息类型时必须显式指定 message_type，否则报错

发布消息 ros2 topic pub：

$ ros2 topic pub /topic base_interfaces_demo/msg/Test '{header: auto, num: 111}' -t 2 -r 10
publisher: beginning loop
publishing #1: base_interfaces_demo.msg.Test(header=..., num=111)

-r N 设频率（默认 1Hz），-t TIMES 发布指定次数后退出，-1 发一条退出，--keep-alive N 在最后一条消息后保持节点存活 N 秒。发布端 QoS 默认 reliable + transient_local，可用 --qos-* 参数覆盖。

其余：ros2 topic find <type> 按类型反查话题；ros2 topic list -v 列出每个话题的发布/订阅端数量与 QoS；ros2 topic info -v <topic> 输出发布者/订阅者的节点名、GUID 与 QoS 配置——排查 QoS 不匹配问题时首选。

ros2 service

$ ros2 service call /add_ints base_interfaces_demo/srv/AddInts '{num1: 5, num2: 4}'
requester: making request: base_interfaces_demo.srv.AddInts_Request(num1=5, num2=4)
response:
base_interfaces_demo.srv.AddInts_Response(sum=9)

ros2 service find <type> 按类型查服务，ros2 service type <name> 输出服务类型，二者互为反向查找。-r N 可按固定频率重复调用。

ros2 action

$ ros2 action send_goal /get_sum base_interfaces_demo/action/Progress '{num: 10}' -f
Waiting for an action server to become available...
Sending goal:
     num: 10
Goal accepted with ID: 606547fc...
Feedback:
    progress: 0.1
...
Result:
    sum: 55
Goal finished with status: SUCCEEDED

-f 回显过程反馈，-t N 设超时。ros2 action list -t、ros2 action info <name> -t 输出动作类型与客户端/服务端归属。

ros2 bag

录制 ros2 bag record：

ros2 bag record [-a] [-e REGEX] [-x EXCLUDE] [-o OUTPUT] [-s STORAGE_ID] \
                [-b MAX_BAG_SIZE] [-d MAX_BAG_DURATION] [--snapshot-mode] [topics ...]

• -a 录制所有话题；-e/-x 按正则包含/排除
• -o 输出目录；-s 指定存储插件，可选值取决于已安装的插件，默认 sqlite3
• -b/-d 按大小/时长自动分割文件；--max-cache-size 缓存上限（默认 100 MiB）
• --snapshot-mode 快照模式：环形缓冲录制，用户触发时才落盘
• 支持 --compression-mode {none,file,message} 与 --compression-format zstd

回放 ros2 bag play：

ros2 bag play [-r RATE] [--topics TOPICS ...] [-l] [--clock [Hz]] [-d DELAY] \
              [--start-offset SECONDS] [--wait-for-all-acked TIMEOUT] bag_path

• -r RATE 变速回放；--topics 只回放指定话题；-l 循环
• --start-offset 从数据包开始后指定秒数处回放
• --clock [Hz] 以指定频率发布 /clock，作为 ROS 时间源回放
• --wait-for-all-acked 等待所有消息被确认（仅 RELIABLE QoS 有效），适合短时间发送大消息的场景
• 回放过程支持键盘控制：空格暂停，左右方向键单步/变速

查看信息 ros2 bag info：

$ ros2 bag info ~/rosbag2_2025_11_13-08_52_36
Files:             rosbag2_2025_11_13-08_52_36_0.db3
Bag size:          65.0 KiB
Storage id:        sqlite3
Duration:          543.96s
Messages:          545
Topic information: Topic: /topic | Type: base_interfaces_demo/msg/Test | Count: 545 | Serialization Format: cdr

转换与重建：ros2 bag convert -i <uri> -o <output.yaml> 按新配置写出数据包（YAML 需含 output_bags 顶级键）；ros2 bag reindex <bag_path> 重建元数据文件。

要点

• ros2 命令族按"命令 + 动词"两级组织，实现基于 rclpy，图信息（节点/话题/服务清单）都来自 DDS 发现——发现未完成时命令结果不全，可用 --spin-time 延长等待
• 守护进程为重复命令提供缓存加速；怀疑缓存信息过期时用 --no-daemon 或 ros2 daemon stop 绕过
• echo/pub 的默认 QoS 与常见发布者不同（订阅端默认 sensor_data、发布端默认 transient_local），排查"看不到消息"时优先检查 QoS
• 参数服务、生命周期服务、组件容器服务都是"节点自动提供的标准服务"，param/lifecycle/component 命令本质上是这些服务的客户端
• bag 录制/回放的大量选项（分割、压缩、快照、变速、跳段）在长时数采与回放调试中常用，值得熟记

相关文章

• ROS2 命令行工具框架：插件系统与节点策略——这些命令从哪里来：entry points 插件系统与直接节点/守护进程两种节点策略
• rosbag2 录制回放：分层架构、时间控制与存储格式——bag 命令背后的五层架构与时间控制机制
• ROS 2 Launch 使用指南：参数、条件与生命周期编排——ros2 launch 启动文件的完整用法